// Copyright 2024 The Google Research Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto2";

package ambient_sensing;

// Next id: 8.
message RecordingCollectionSensorOptions {
  // Required. Sensor type that is being configured.
  optional string type = 1;
  // Required. Sensor subtype that is being configured.
  optional string subtype = 2;

  // Each element of a stream must be a vector with this many elements.
  // Not setting the value, or setting a negative value, would result in not
  // enforcing any particular vector size.
  optional int32 required_dims = 3 [default = -1];

  // Option for the MergeSensorDataIntoAnnotatedRecordingCollectionCalculator.
  // Dimensionality of the windowed data being merged. This should match
  // enforce_input_dims in WindowCalculator. For example, if window_dims is 2
  // and the input data is {1, 2, 3, 4, 5, 6}, then the calculator would create
  // a window with 3 datapoints, each with dimensionality 2:
  // {1, 2}, {3, 4}, {5, 6}
  optional int32 window_dims = 7;

  // Option for the ExtractSensorDataFromAnnotatedRecordingCollectionCalculator.
  // If the sensor stream has multiple values per timestamp, you can configure
  // this option to only output the last one, and don't output others. For
  // example, if duplicate_timestamps_handling_strategy is not set, then the
  // calculator might produce a stream: a@t1 b@t1 c@t2 d@t3 e@t3.
  // If duplicate_timestamps_handling_strategy is set to RAISE_ERROR, then the
  // calculator would return an error.
  // If duplicate_timestamps_handling_strategy is KEEP_LAST_VALUE, then the
  // produced values would be: b@t1 c@t2 e@t3.
  //
  // This is a required option for the
  // ExtractSensorDataFromAnnotatedRecordingCollectionCalculator.
  enum DuplicateTimestampsHandlingStrategy {
    UNKNOWN = 0;
    // If duplicate timestamps are found, an error is raised.
    // Note that Drishti allows writing out values with duplicate timestamps,
    // delaying the failure to a time when an attempt is made to read values
    // from the stream. This setting in a sense doesn't change this behavior,
    // but makes the failure earlier.
    RAISE_ERROR = 1;
    // If duplicate timestamps are found, all values except for the last one are
    // dropped. For example, if there were values v1@t1, v2@t1, v3@t1, then only
    // v3 will be produced for that timestamp.
    KEEP_LAST_VALUE = 2;
  }
  optional DuplicateTimestampsHandlingStrategy
      duplicate_timestamps_handling_strategy = 4;

  // Optional default value for the sensor stream, if no data is provided for it
  // at the first timestamp. If not set, no default value will be provided.
  // Otherwise, if required_dims is set, default_value.size has to match
  // required_dims. In case required_dims is not set, the default value is
  // passed without further checking. Useful for streams that go into
  // PacketClonerCalculator. Do not set default_values for streams fed into
  // PacketResamplerCalculator.
  repeated float default_value = 5;
}
